GitHub CLI (gh)

Expert guidance for GitHub CLI operations and workflows.

Installation & Setup

bash
1# Login to GitHub
2gh auth login
3
4# Check authentication status
5gh auth status
6
7# Configure git to use gh as credential helper
8gh auth setup-git

Pull Requests

Creating PRs

bash
1# Create PR interactively
2gh pr create
3
4# Create PR with title and body
5gh pr create --title "Add feature" --body "Description"
6
7# Create PR to specific branch
8gh pr create --base main --head feature-branch
9
10# Create draft PR
11gh pr create --draft
12
13# Create PR from current branch
14gh pr create --fill  # Uses commit messages

Viewing PRs

bash
1# List PRs
2gh pr list
3
4# List my PRs
5gh pr list --author @me
6
7# View PR details
8gh pr view 123
9
10# View PR in browser
11gh pr view 123 --web
12
13# View PR diff
14gh pr diff 123
15
16# Check PR status
17gh pr status

Managing PRs

bash
1# Checkout PR locally
2gh pr checkout 123
3
4# Review PR
5gh pr review 123 --approve
6gh pr review 123 --comment --body "Looks good!"
7gh pr review 123 --request-changes --body "Please fix X"
8
9# Merge PR
10gh pr merge 123
11gh pr merge 123 --squash
12gh pr merge 123 --rebase
13gh pr merge 123 --merge
14
15# Close PR
16gh pr close 123
17
18# Reopen PR
19gh pr reopen 123
20
21# Ready draft PR
22gh pr ready 123

PR Checks

bash
1# View PR checks
2gh pr checks 123
3
4# Watch PR checks
5gh pr checks 123 --watch

Issues

Creating Issues

bash
1# Create issue interactively
2gh issue create
3
4# Create issue with title and body
5gh issue create --title "Bug report" --body "Description"
6
7# Create issue with labels
8gh issue create --title "Bug" --label bug,critical
9
10# Assign issue
11gh issue create --title "Task" --assignee @me

Viewing Issues

bash
1# List issues
2gh issue list
3
4# List my issues
5gh issue list --assignee @me
6
7# List by label
8gh issue list --label bug
9
10# View issue details
11gh issue view 456
12
13# View in browser
14gh issue view 456 --web

Managing Issues

bash
1# Close issue
2gh issue close 456
3
4# Reopen issue
5gh issue reopen 456
6
7# Edit issue
8gh issue edit 456 --title "New title"
9gh issue edit 456 --add-label bug
10gh issue edit 456 --add-assignee @user
11
12# Comment on issue
13gh issue comment 456 --body "Update"

Repository Operations

Repository Info

bash
1# View repository
2gh repo view
3
4# View in browser
5gh repo view --web
6
7# Clone repository
8gh repo clone owner/repo
9
10# Fork repository
11gh repo fork owner/repo
12
13# List repositories
14gh repo list owner

Repository Management

bash
1# Create repository
2gh repo create my-repo --public
3gh repo create my-repo --private
4
5# Delete repository
6gh repo delete owner/repo
7
8# Sync fork
9gh repo sync owner/repo
10
11# Set default repository
12gh repo set-default

Workflows & Actions

Viewing Workflows

bash
1# List workflows
2gh workflow list
3
4# View workflow runs
5gh run list
6
7# View specific run
8gh run view 789
9
10# Watch run
11gh run watch 789
12
13# View run logs
14gh run view 789 --log

Managing Workflows

bash
1# Trigger workflow
2gh workflow run workflow.yml
3
4# Cancel run
5gh run cancel 789
6
7# Rerun workflow
8gh run rerun 789
9
10# Download artifacts
11gh run download 789

Releases

Creating Releases

bash
1# Create release
2gh release create v1.0.0
3
4# Create release with notes
5gh release create v1.0.0 --notes "Release notes"
6
7# Create release with files
8gh release create v1.0.0 dist/*.tar.gz
9
10# Create draft release
11gh release create v1.0.0 --draft
12
13# Generate release notes automatically
14gh release create v1.0.0 --generate-notes

Managing Releases

bash
1# List releases
2gh release list
3
4# View release
5gh release view v1.0.0
6
7# Download release assets
8gh release download v1.0.0
9
10# Delete release
11gh release delete v1.0.0

Version Management (pki-manager specific)

IMPORTANT: When creating a new release for this project, you MUST bump the version in ALL THREE package.json files:

• package.json (root - authoritative source)
• frontend/package.json
• backend/package.json

Version Bump Types (Semantic Versioning)

Pre-Release Workflow

Before creating a release, you MUST:

1. Check current version in root package.json
2. Determine bump type based on changes since last release
3. Update ALL package.json files with the new version
4. Commit version changes with message: chore: bump version to vX.Y.Z
5. Create git tag: git tag vX.Y.Z
6. Push tag: git push origin vX.Y.Z
7. Create GitHub release: gh release create vX.Y.Z --generate-notes

Complete Release Workflow

bash
1# 1. Determine current version
2cat package.json | grep '"version"'
3# Output: "version": "1.2.0"
4
5# 2. Update versions in all package.json files
6# For patch bump (1.2.0 → 1.2.1):
7NEW_VERSION="1.2.1"
8
9# Edit package.json (root)
10# Edit frontend/package.json
11# Edit backend/package.json
12# All three must have the same version!
13
14# 3. Commit version bump
15git add package.json frontend/package.json backend/package.json
16git commit -m "chore: bump version to v${NEW_VERSION}"
17
18# 4. Create and push tag
19git tag "v${NEW_VERSION}"
20git push origin main
21git push origin "v${NEW_VERSION}"
22
23# 5. Create GitHub release with auto-generated notes
24gh release create "v${NEW_VERSION}" --generate-notes
25
26# Or with custom notes
27gh release create "v${NEW_VERSION}" --notes "## What's Changed
28- Feature A
29- Bug fix B
30- Improvement C"

Version Synchronization Rules

CRITICAL: All three package.json files MUST have matching versions:

Checking Version Consistency

bash
1# Quick check all versions
2echo "Root: $(cat package.json | grep '"version"' | head -1)"
3echo "Frontend: $(cat frontend/package.json | grep '"version"' | head -1)"
4echo "Backend: $(cat backend/package.json | grep '"version"' | head -1)"

Release Checklist

Before releasing, verify:

• All tests pass (pnpm test)
• Build succeeds (pnpm build)
• All three package.json versions match
• Changes are committed to main branch
• No uncommitted changes (git status)
• Previous release tag exists for comparison

Gists

bash
1# Create gist
2gh gist create file.txt
3
4# Create gist from stdin
5echo "content" | gh gist create -
6
7# List gists
8gh gist list
9
10# View gist
11gh gist view <gist-id>
12
13# Edit gist
14gh gist edit <gist-id>
15
16# Delete gist
17gh gist delete <gist-id>

Advanced Features

Aliases

bash
1# Create alias
2gh alias set pv "pr view"
3gh alias set bugs "issue list --label bug"
4
5# List aliases
6gh alias list
7
8# Use alias
9gh pv 123

API Access

bash
1# Make API call
2gh api repos/:owner/:repo/issues
3
4# With JSON data
5gh api repos/:owner/:repo/issues -f title="Bug" -f body="Description"
6
7# Paginated results
8gh api --paginate repos/:owner/:repo/issues

Extensions

bash
1# List extensions
2gh extension list
3
4# Install extension
5gh extension install owner/gh-extension
6
7# Upgrade extensions
8gh extension upgrade --all

Common Workflows

Code Review Workflow

bash
1# List PRs assigned to you
2gh pr list --assignee @me
3
4# Checkout PR for testing
5gh pr checkout 123
6
7# Run tests, review code...
8
9# Approve PR
10gh pr review 123 --approve --body "LGTM!"
11
12# Merge PR
13gh pr merge 123 --squash

Quick PR Creation

bash
1# Create feature branch, make changes, commit
2git checkout -b feature/new-feature
3# ... make changes ...
4git add .
5git commit -m "Add new feature"
6git push -u origin feature/new-feature
7
8# Create PR from commits
9gh pr create --fill
10
11# View PR
12gh pr view --web

Issue Triage

bash
1# List open issues
2gh issue list
3
4# Add labels to issues
5gh issue edit 456 --add-label needs-triage
6gh issue edit 456 --add-label bug
7
8# Assign issue
9gh issue edit 456 --add-assignee @developer

Configuration

bash
1# Set default editor
2gh config set editor vim
3
4# Set default git protocol
5gh config set git_protocol ssh
6
7# View configuration
8gh config list
9
10# Set browser
11gh config set browser firefox

Tips

1. Use --web flag: Open items in browser for detailed view
2. Interactive prompts: Most commands work interactively if you omit parameters
3. Filters: Use --author, --label, --state to filter lists
4. JSON output: Add --json flag for scriptable output
5. Template repos: Use gh repo create --template for templates
6. Auto-merge: Enable with gh pr merge --auto